<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xml:lang="en" xmlns="http://www.w3.org/1999/xhtml" lang="en"><head>

	
		<meta http-equiv="Content-type" content="text/html; charset=UTF-8">
		<meta http-equiv="Content-Language" content="en-us">

		<title>Django | Related objects reference | Django Documentation</title>

		<meta name="ROBOTS" content="ALL">
		<meta http-equiv="imagetoolbar" content="no">
		<meta name="MSSmartTagsPreventParsing" content="true">
		<meta name="Copyright" content="This site's design and contents Copyright (c) 2005  Lawrence Journal-World.">

		<meta name="keywords" content="Python, Django, framework, open-source">
		<meta name="description" content="Django is a high-level Python Web framework that encourages rapid development and clean, pragmatic design.">

		<link href="Django%20%7C%20Related%20objects%20reference%20%7C%20Django%20Documentation_files/base.css" rel="stylesheet" type="text/css" media="screen">
		<link href="Django%20%7C%20Related%20objects%20reference%20%7C%20Django%20Documentation_files/print.css" rel="stylesheet" type="text/css" media="print">
      
  
  <style type="text/css" media="screen">
    #docs-search {
      color: #000;
      float: right;
    }
    #docs-search form {
      font-size: 92%;
      margin: 0;
      padding: 1em 1em 0;
      white-space: nowrap;
    }
    form.search ul {
      list-style: none;
      margin: 0;
      padding: 0;
    }
    form.search li {
      display: inline;
      padding-right: 1em;
    }
    form.search .query {
      width: 18em;
    }
  </style>
  <link rel="stylesheet" href="Django%20%7C%20Related%20objects%20reference%20%7C%20Django%20Documentation_files/pygments.css" type="text/css">

	</head><body id="documentation" class="default">

	<div id="container">
		<div id="header">
			<h1 id="logo"><a href="http://www.djangoproject.com/"><img src="Django%20%7C%20Related%20objects%20reference%20%7C%20Django%20Documentation_files/hdr_logo.gif" alt="Django"></a></h1>
			<ul id="nav-global">
				<li id="nav-homepage"><a href="http://www.djangoproject.com/">Home</a></li>
				<li id="nav-download"><a href="http://www.djangoproject.com/download/">Download</a></li>
				<li id="nav-documentation"><a href="http://docs.djangoproject.com/">Documentation</a></li>
				<li id="nav-weblog"><a href="http://www.djangoproject.com/weblog/">Weblog</a></li>
				<li id="nav-community"><a href="http://www.djangoproject.com/community/">Community</a></li>
				<li id="nav-code"><a href="http://code.djangoproject.com/">Code</a></li>
			</ul>
		</div>
		<!-- END Header -->
		<div id="billboard">
  <h2><a href="http://docs.djangoproject.com/en/1.0/">Django documentation</a></h2>
</div>
		<div id="columnwrap">
			
		<div id="content-main">
		


  <h2 class="deck">
  
    This document describes Django version 1.0. For development documentation, 
    <a href="http://docs.djangoproject.com/en/dev/ref/models/relations/">go here</a>.
  
  </h2>
  <div class="section" id="s-related-objects-reference">
<span id="s-ref-models-relations"></span><span id="related-objects-reference"></span><span id="ref-models-relations"></span><h1>Related objects reference<a class="headerlink" href="#related-objects-reference" title="Permalink to this headline">¶</a></h1>
<p>This document describes extra methods available on managers when
used in a one-to-many or many-to-many related context. This happens in
two cases:</p>
<ul>
<li><p class="first">The “other side” of a <tt class="docutils literal"><span class="pre">ForeignKey</span></tt> relation. That is:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Reporter</span><span class="p">(</span><span class="n">models</span><span class="o">.</span><span class="n">Model</span><span class="p">):</span>
    <span class="o">...</span>

<span class="k">class</span> <span class="nc">Article</span><span class="p">(</span><span class="n">models</span><span class="o">.</span><span class="n">Model</span><span class="p">):</span>
    <span class="n">reporter</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">ForeignKey</span><span class="p">(</span><span class="n">Reporter</span><span class="p">)</span>
</pre></div>
</div>
<p>In the above example, the methods below will be available on
the manager <tt class="docutils literal"><span class="pre">reporter.article_set</span></tt>.</p>
</li>
<li><p class="first">Both sides of a <tt class="docutils literal"><span class="pre">ManyToManyField</span></tt> relation:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Topping</span><span class="p">(</span><span class="n">models</span><span class="o">.</span><span class="n">Model</span><span class="p">):</span>
    <span class="o">...</span>

<span class="k">class</span> <span class="nc">Pizza</span><span class="p">(</span><span class="n">models</span><span class="o">.</span><span class="n">Model</span><span class="p">):</span>
    <span class="n">toppings</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">ManyToManyField</span><span class="p">(</span><span class="n">Topping</span><span class="p">)</span>
</pre></div>
</div>
<p>In this example, the methods below will be available both on
<tt class="docutils literal"><span class="pre">topping.pizza_set</span></tt> and on <tt class="docutils literal"><span class="pre">pizza.toppings</span></tt>.</p>
</li>
</ul>
<dl class="method">
<dt id="django.db.models.QuerySet.add">
<!--[django.db.models.QuerySet.add]--><tt class="descclassname">QuerySet.</tt><tt class="descname">add</tt>(<em>obj1</em><span class="optional">[</span>, <em>obj2</em>, <em>...</em><span class="optional">]</span>)<a class="headerlink" href="#django.db.models.QuerySet.add" title="Permalink to this definition">¶</a></dt>
<dd><p>Adds the specified model objects to the related object set.</p>
<p>Example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">b</span> <span class="o">=</span> <span class="n">Blog</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="nb">id</span><span class="o">=</span><span class="mf">1</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">e</span> <span class="o">=</span> <span class="n">Entry</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="nb">id</span><span class="o">=</span><span class="mf">234</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">b</span><span class="o">.</span><span class="n">entry_set</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">e</span><span class="p">)</span> <span class="c"># Associates Entry e with Blog b.</span>
</pre></div>
</div>
</dd></dl>

<dl class="method">
<dt id="django.db.models.QuerySet.create">
<!--[django.db.models.QuerySet.create]--><tt class="descclassname">QuerySet.</tt><tt class="descname">create</tt>(<em>**kwargs</em>)<a class="headerlink" href="#django.db.models.QuerySet.create" title="Permalink to this definition">¶</a></dt>
<dd><p>Creates a new object, saves it and puts it in the related object set.
Returns the newly created object:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">b</span> <span class="o">=</span> <span class="n">Blog</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="nb">id</span><span class="o">=</span><span class="mf">1</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">e</span> <span class="o">=</span> <span class="n">b</span><span class="o">.</span><span class="n">entry_set</span><span class="o">.</span><span class="n">create</span><span class="p">(</span>
<span class="gp">... </span>    <span class="n">headline</span><span class="o">=</span><span class="s">'Hello'</span><span class="p">,</span>
<span class="gp">... </span>    <span class="n">body_text</span><span class="o">=</span><span class="s">'Hi'</span><span class="p">,</span>
<span class="gp">... </span>    <span class="n">pub_date</span><span class="o">=</span><span class="n">datetime</span><span class="o">.</span><span class="n">date</span><span class="p">(</span><span class="mf">2005</span><span class="p">,</span> <span class="mf">1</span><span class="p">,</span> <span class="mf">1</span><span class="p">)</span>
<span class="gp">... </span><span class="p">)</span>

<span class="go"># No need to call e.save() at this point -- it's already been saved.</span>
</pre></div>
</div>
<p>This is equivalent to (but much simpler than):</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">b</span> <span class="o">=</span> <span class="n">Blog</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="nb">id</span><span class="o">=</span><span class="mf">1</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">e</span> <span class="o">=</span> <span class="n">Entry</span><span class="p">(</span>
<span class="go">....     blog=b,</span>
<span class="go">....     headline='Hello',</span>
<span class="go">....     body_text='Hi',</span>
<span class="go">....     pub_date=datetime.date(2005, 1, 1)</span>
<span class="go">.... )</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">e</span><span class="o">.</span><span class="n">save</span><span class="p">(</span><span class="n">force_insert</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
</pre></div>
</div>
<p>Note that there's no need to specify the keyword argument of the model that
defines the relationship. In the above example, we don't pass the parameter
<tt class="docutils literal"><span class="pre">blog</span></tt> to <tt class="docutils literal"><span class="pre">create()</span></tt>. Django figures out that the new <tt class="docutils literal"><span class="pre">Entry</span></tt> object's
<tt class="docutils literal"><span class="pre">blog</span></tt> field should be set to <tt class="docutils literal"><span class="pre">b</span></tt>.</p>
</dd></dl>

<dl class="method">
<dt id="django.db.models.QuerySet.remove">
<!--[django.db.models.QuerySet.remove]--><tt class="descclassname">QuerySet.</tt><tt class="descname">remove</tt>(<em>obj1</em><span class="optional">[</span>, <em>obj2</em>, <em>...</em><span class="optional">]</span>)<a class="headerlink" href="#django.db.models.QuerySet.remove" title="Permalink to this definition">¶</a></dt>
<dd><p>Removes the specified model objects from the related object set:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">b</span> <span class="o">=</span> <span class="n">Blog</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="nb">id</span><span class="o">=</span><span class="mf">1</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">e</span> <span class="o">=</span> <span class="n">Entry</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="nb">id</span><span class="o">=</span><span class="mf">234</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">b</span><span class="o">.</span><span class="n">entry_set</span><span class="o">.</span><span class="n">remove</span><span class="p">(</span><span class="n">e</span><span class="p">)</span> <span class="c"># Disassociates Entry e from Blog b.</span>
</pre></div>
</div>
<p>In order to prevent database inconsistency, this method only exists on
<tt class="docutils literal"><span class="pre">ForeignKey</span></tt> objects where <tt class="docutils literal"><span class="pre">null=True</span></tt>. If the related field can't be
set to <tt class="xref docutils literal"><span class="pre">None</span></tt> (<tt class="docutils literal"><span class="pre">NULL</span></tt>), then an object can't be removed from a relation
without being added to another. In the above example, removing <tt class="docutils literal"><span class="pre">e</span></tt> from
<tt class="docutils literal"><span class="pre">b.entry_set()</span></tt> is equivalent to doing <tt class="docutils literal"><span class="pre">e.blog</span> <span class="pre">=</span> <span class="pre">None</span></tt>, and because the
<tt class="docutils literal"><span class="pre">blog</span></tt> <tt class="docutils literal"><span class="pre">ForeignKey</span></tt> doesn't have <tt class="docutils literal"><span class="pre">null=True</span></tt>, this is invalid.</p>
</dd></dl>

<dl class="method">
<dt id="django.db.models.QuerySet.clear">
<!--[django.db.models.QuerySet.clear]--><tt class="descclassname">QuerySet.</tt><tt class="descname">clear</tt>()<a class="headerlink" href="#django.db.models.QuerySet.clear" title="Permalink to this definition">¶</a></dt>
<dd><p>Removes all objects from the related object set:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">b</span> <span class="o">=</span> <span class="n">Blog</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="nb">id</span><span class="o">=</span><span class="mf">1</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">b</span><span class="o">.</span><span class="n">entry_set</span><span class="o">.</span><span class="n">clear</span><span class="p">()</span>
</pre></div>
</div>
<p>Note this doesn't delete the related objects -- it just disassociates them.</p>
<p>Just like <tt class="docutils literal"><span class="pre">remove()</span></tt>, <tt class="docutils literal"><span class="pre">clear()</span></tt> is only available on <tt class="docutils literal"><span class="pre">ForeignKey</span></tt>s
where <tt class="docutils literal"><span class="pre">null=True</span></tt>.</p>
</dd></dl>

</div>



<div id="content-secondary">
  <h2 id="comments">Questions/Feedback</h2>
  <p>Having trouble? We'd like to help!</p>
  <ul>
    <li>
      Try the <a href="http://docs.djangoproject.com/en/dev/faq/">FAQ</a> — it's got answers to many common
      questions.
    </li>
    <li>
      Search for information in the <a href="http://groups.google.com/group/django-users/">archives of the
      django-users mailing list</a>, or <a href="http://groups.google.com/group/django-users/">post a question</a>.
    </li>
    <li>
      Ask a question in the <a href="irc://irc.freenode.net/">#django IRC
      channel</a>, or search the <a href="http://oebfare.com/logger/django/">IRC
      logs</a> to see if its been asked before.
    </li>
    <li>
      If you notice errors with this documentation, please <a href="http://code.djangoproject.com/simpleticket?component=Documentation">
      open a ticket</a> and let us know! Please only use the ticket tracker for
      criticisms and improvements on the docs. For tech support, use the
      resources above.
    </li>
  </ul>
</div>

		</div>
		<!-- END #content-main -->
		<div id="content-related" class="sidebar">
		
  
    <h2>Contents</h2>
    
      <ul>
<li><a class="reference external" href="">Related objects reference</a></li>
</ul>

    
  
  
  
    <h2>Search</h2>
    
    <form action="/en/1.0/search/" id="search" class="search">
  <div>
    <input name="cx" value="009763561546736975936:e88ek0eurf4" type="hidden">
    <input name="cof" value="FORID:11" type="hidden">
    <input name="ie" value="UTF-8" type="hidden">
    <input name="hl" value="" type="hidden">
    <input style="background: rgb(255, 255, 255) url(http://www.google.com/coop/intl/en/images/google_custom_search_watermark.gif) no-repeat scroll left center; -moz-background-clip: -moz-initial; -moz-background-origin: -moz-initial; -moz-background-inline-policy: -moz-initial;" id="id_search_q" class="query" name="q" type="text">
    <input name="sa" class="submit" value="Search" type="submit">
    <ul>
<li><label for="id_search_as_q_0"><input checked="checked" id="id_search_as_q_0" value="more:dev_docs" name="as_q" type="radio"> Latest</label></li>
<li><label for="id_search_as_q_1"><input id="id_search_as_q_1" value="more:1.0_docs" name="as_q" type="radio"> 1.0</label></li>
<li><label for="id_search_as_q_2"><input id="id_search_as_q_2" value="more:0.96_docs" name="as_q" type="radio"> 0.96</label></li>
<li><label for="id_search_as_q_3"><input id="id_search_as_q_3" value="more:all_docs" name="as_q" type="radio"> All</label></li>
</ul>
  </div>
</form>
<script type="text/javascript" src="Django%20%7C%20Related%20objects%20reference%20%7C%20Django%20Documentation_files/brand.html"></script>
  
  
  
    <h2>Browse</h2>
    <ul>
      
        
          <li>Prev: <a href="http://docs.djangoproject.com/en/1.0/ref/models/fields/">Model field reference</a></li>
        
        
          <li>Next: <a href="http://docs.djangoproject.com/en/1.0/ref/models/options/">Model <tt class="docutils literal docutils literal"><span class="pre">Meta</span></tt> options</a></li>
        
        <li><a href="http://docs.djangoproject.com/en/1.0/contents/">Table of contents</a></li>
        
          <li><a href="http://docs.djangoproject.com/en/1.0/genindex/">General Index</a></li>
        
          <li><a href="http://docs.djangoproject.com/en/1.0/modindex/">Global Module Index</a></li>
        
      
    </ul>
  
  
  
    <h2>You are here:</h2>
    <ul>
      
        <li>
          <a href="http://docs.djangoproject.com/en/1.0/">Django 1.0 documentation</a>
          
            <ul><li><a href="http://docs.djangoproject.com/en/1.0/ref/">API Reference</a>
          
            <ul><li><a href="http://docs.djangoproject.com/en/1.0/ref/models/">Models</a>
          
          <ul><li>Related objects reference</li></ul>
          </li></ul></li></ul>
        </li>
      
    </ul>
  
  
  
    <h3>Last update:</h3>
    <div>May 23, 2009, 8:15 a.m. (<a href="http://www.timeanddate.com/worldclock/city.html?n=64">CDT</a>)</div>
  

		</div>
		<!-- END #content-related -->

		</div>
		<!-- END #content -->
		<div id="footer">
			<p>© 2005-2009 <a href="http://www.djangoproject.com/foundation/">Django Software Foundation</a> unless otherwise noted. Django is a registered trademark of the Django Software Foundation. 
			Hosting graciously provided by <a href="http://mediatemple.net/">
			<img style="vertical-align: middle; position: relative; top: -1px;" src="Django%20%7C%20Related%20objects%20reference%20%7C%20Django%20Documentation_files/mt.png" alt="media temple"></a>
			</p>
		</div>
		<!-- END #footer -->
	</div>
	<!-- END #container -->
	</body></html>